<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Ex_rep_base: a TCP/IP based communication infrastructure</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 13.  Berkeley DB Replication" />
    <link rel="prev" href="rep_ex.html" title="Ex_rep: a replication example" />
    <link rel="next" href="rep_ex_rq.html" title="Ex_rep_base: putting it all together" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Ex_rep_base: a TCP/IP based communication infrastructure</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_ex.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 13.  Berkeley DB Replication </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_ex_rq.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="rep_ex_comm"></a>Ex_rep_base: a TCP/IP based communication infrastructure</h2>
          </div>
        </div>
      </div>
      <p>
        Base API applications must implement a communication
        infrastructure. The communication infrastructure consists of
        three parts: a way to map environment IDs to particular sites,
        the functions to send and receive messages, and the
        application architecture that supports the particular
        communication infrastructure used (for example, individual
        threads per communicating site, a shared message handler for
        all sites, a hybrid solution). The communication
        infrastructure for ex_rep_base is implemented in the file
        <code class="filename">ex_rep/base/rep_net.c</code>, and each part
        of that infrastructure is described as follows.
    </p>
      <p>
        Ex_rep_base maintains a table of environment ID to TCP/IP
        port mappings. A pointer to this table is stored in a
        structure pointed to by the app_private field of the <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
        object so it can be accessed by any function that has the
        database environment handle. The table is represented by a
        machtab_t structure which contains a reference to a linked
        list of member_t's, both of which are defined in
        <code class="filename">ex_rep/base/rep_net.c</code>. Each member_t
        contains the host and port identification, the environment ID,
        and a file descriptor.
    </p>
      <p>
        This design is particular to this application and
        communication infrastructure, but provides an indication of
        the sort of functionality that is needed to maintain the
        application-specific state for a TCP/IP-based infrastructure.
        The goal of the table and its interfaces is threefold: First,
        it must guarantee that given an environment ID, the send
        function can send a message to the appropriate place. Second,
        when given the special environment ID <a href="../api_reference/C/reptransport.html#transport_DB_EID_BROADCAST" class="olink">DB_EID_BROADCAST</a>, the
        send function can send messages to all the machines in the
        group. Third, upon receipt of an incoming message, the receive
        function can correctly identify the sender and pass the
        appropriate environment ID to the <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV-&gt;rep_process_message()</a> method.
    </p>
      <p>
        Mapping a particular environment ID to a specific port is
        accomplished by looping through the linked list until the
        desired environment ID is found. Broadcast communication is
        implemented by looping through the linked list and sending to
        each member found. Since each port communicates with only a
        single other environment, receipt of a message on a particular
        port precisely identifies the sender.
    </p>
      <p>
        This is implemented in the quote_send, quote_send_broadcast
        and quote_send_one functions, which can be found in
        <code class="filename">ex_rep/base/rep_net.c</code>.
    </p>
      <p>
        The example provided is merely one way to satisfy these
        requirements, and there are alternative implementations as
        well. For instance, instead of associating separate socket
        connections with each remote environment, an application might
        instead label each message with a sender identifier; instead
        of looping through a table and sending a copy of a message to
        each member of the replication group, the application could
        send a single message using a broadcast protocol.
    </p>
      <p>
        The quote_send function is passed as the callback to
        <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a>; Berkeley DB automatically sends messages as
        needed for replication. The receive function is a mirror to
        the quote_send_one function. It is not a callback function
        (the application is responsible for collecting messages and
        calling <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV-&gt;rep_process_message()</a> on them as is convenient). In the sample
        application, all messages transmitted are Berkeley DB messages
        that get handled by <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV-&gt;rep_process_message()</a>, however, this is not always
        going to be the case. The application may want to pass its own
        messages across the same channels, distinguish between its own
        messages and those of Berkeley DB, and then pass only the
        Berkeley DB ones to <a href="../api_reference/C/repmessage.html" class="olink">DB_ENV-&gt;rep_process_message()</a>.
    </p>
      <p>
        The final component of the communication infrastructure is
        the process model used to communicate with all the sites in
        the replication group. Each site creates a thread of control
        that listens on its designated socket (as specified by the
        <span class="bold"><strong>-l</strong></span> command line argument)
        and then creates a new channel for each site that contacts it.
        In addition, each site explicitly connects to the sites
        specified in the <span class="bold"><strong>-r</strong></span> and
        <span class="bold"><strong>-R</strong></span> command line
        arguments. This is a fairly standard TCP/IP process
        architecture and is implemented by the connect_thread,
        connect_all and connect_site functions in
        <code class="filename">ex_rep/base/rep_msg.c</code> and supporting
        functions in
        <code class="filename">ex_rep/base/rep_net.c</code>.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_ex.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_ex_rq.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Ex_rep: a replication example </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Ex_rep_base: putting it all
        together</td>
        </tr>
      </table>
    </div>
  </body>
</html>
